React useFormStatus: Komplexní průvodce správou stavu formulářů

Hook useFormStatus, představený v Reactu 18, poskytuje výkonný a efektivní způsob správy stavu odesílání formulářů v rámci React Server Components. Tento hook je speciálně navržen pro práci se serverovými akcemi (server actions) a nabízí bezproblémovou integraci pro zpracování odeslání formulářů přímo na serveru. Zjednodušuje proces sledování stavu odeslání formuláře a poskytuje cenné informace, například zda formulář čeká na zpracování, byl úspěšně odeslán, nebo došlo k chybě. Tento průvodce prozkoumává možnosti useFormStatus, jeho výhody a praktické příklady demonstrující jeho použití v různých scénářích.

Porozumění serverovým akcím a useFormStatus

Než se ponoříme do useFormStatus, je klíčové porozumět React Server Components a serverovým akcím. Serverové akce vám umožňují definovat funkce, které běží na serveru a jsou přímo dostupné z vašich React komponent. To umožňuje zpracovávat odesílání formulářů, načítání dat a další operace na straně serveru bez nutnosti samostatného API endpointu.

Hook useFormStatus pak poskytuje přehled o provádění těchto serverových akcí spuštěných odesláním formuláře.

Co je useFormStatus?

useFormStatus je React hook, který vrací objekt obsahující informace o stavu posledního odeslání formuláře. Tyto informace zahrnují:

• pending: Booleovská hodnota indikující, zda se formulář právě odesílá.
• data: Objekt FormData spojený s odesláním.
• method: HTTP metoda použitá pro odeslání (obvykle 'POST').
• action: Funkce serverové akce, která byla spuštěna.

Výhody použití useFormStatus

Využití useFormStatus nabízí několik klíčových výhod:

• Zjednodušená správa stavu: Eliminuje potřebu manuální správy stavu pro sledování stavu odeslání formuláře. Hook se automaticky aktualizuje s postupem odesílání.
• Zlepšený uživatelský zážitek: Poskytuje uživatelům zpětnou vazbu v reálném čase, jako je zobrazování indikátorů načítání během zpracování formuláře nebo zobrazení chybových hlášení při selhání.
• Čistý kód: Podporuje deklarativnější a udržovatelnější kódovou základnu oddělením logiky odesílání formuláře od vykreslování komponenty.
• Bezproblémová integrace se serverovými akcemi: Navržen tak, aby dokonale fungoval se serverovými akcemi, což usnadňuje zpracování odeslání formulářů přímo na serveru.

Praktické příklady použití useFormStatus

Prozkoumejme několik praktických příkladů, které ilustrují použití useFormStatus v různých scénářích.

Základní odeslání formuláře s indikátorem načítání

Tento příklad demonstruje jednoduchý formulář s indikátorem načítání, který se zobrazuje během odesílání formuláře.

Serverová akce (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulace zpoždění pro demonstraci stavu načítání
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Formulář odeslán se jménem:', name);
  return { message: `Formulář úspěšně odeslán se jménem: ${name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      Jméno:
      
      
        {pending ? 'Odesílám...' : 'Odeslat'}
      
    
  )
}

export default FormComponent

V tomto příkladu je vlastnost pending z useFormStatus použita k deaktivaci vstupního pole a tlačítka během odesílání formuláře a k zobrazení zprávy "Odesílám...".

Zpracování úspěšných a chybových stavů

Tento příklad ukazuje, jak zpracovat úspěšné a chybové stavy po odeslání formuláře.

Serverová akce (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulace zpoždění
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('Jméno je povinné');
  }

  console.log('Formulář odeslán se jménem:', name);
  return { message: `Formulář úspěšně odeslán se jménem: ${name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Jméno:
      
      
        {pending ? 'Odesílám...' : 'Odeslat'}
      
      {pending && 
Odesílám...
}
      {message && 
{message}
}
      {error && 
Chyba: {error}
}
    
  )
}

export default FormComponent

V tomto příkladu je v funkci handleSubmit použit blok try/catch. Pokud serverová akce vyvolá chybu, je zachycena a zobrazena uživateli. Po úspěšném odeslání se zobrazí zpráva o úspěchu.

Použití FormData pro komplexní data

useFormStatus bezproblémově spolupracuje s FormData, což vám umožňuje snadno zpracovávat složité datové struktury. Zde je příklad, který ukazuje, jak nahrávat soubory.

Serverová akce (actions.js):

'use server'

export async function uploadFile(formData) {
  // Simulace zpracování souboru
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Nebyl nahrán žádný soubor');
  }

  console.log('Soubor nahrán:', file.name);
  return { message: `Soubor byl úspěšně nahrán: ${file.name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Nahrát soubor:
      
      
        {pending ? 'Nahrávám...' : 'Nahrát'}
      
      {pending && 
Nahrávám...
}
      {message && 
{message}
}
      {error && 
Chyba: {error}
}
    
  )
}

export default FormComponent

Tento příklad ukazuje, jak zpracovávat nahrávání souborů pomocí FormData. Serverová akce získá soubor z objektu FormData a zpracuje ho. Hook useFormStatus spravuje stav načítání během nahrávání souboru.

Osvědčené postupy pro použití useFormStatus

Chcete-li maximalizovat výhody useFormStatus, zvažte tyto osvědčené postupy:

• Poskytujte jasnou zpětnou vazbu uživateli: Použijte stav pending k zobrazení informativních indikátorů načítání a deaktivujte prvky formuláře, abyste zabránili vícenásobnému odeslání.
• Zpracovávejte chyby elegantně: Implementujte zpracování chyb pro zachycení výjimek ve vašich serverových akcích a zobrazujte uživatelsky přívětivá chybová hlášení.
• Validujte data na serveru: Provádějte validaci na straně serveru, abyste zajistili integritu a bezpečnost dat.
• Udržujte serverové akce stručné: Zaměřte serverové akce na konkrétní úkoly, abyste zlepšili výkon a udržovatelnost.
• Zvažte přístupnost: Ujistěte se, že vaše formuláře jsou přístupné poskytnutím správných popisků, ARIA atributů a podpory navigace pomocí klávesnice.

Pokročilé případy použití

Kromě základních příkladů lze useFormStatus použít i ve složitějších scénářích:

• Progresivní vylepšení (Progressive Enhancement): Použijte serverové akce a useFormStatus k postupnému vylepšování vašich formulářů, poskytující základní zážitek pro uživatele s vypnutým JavaScriptem a bohatší zážitek pro ty s povoleným JavaScriptem.
• Optimistické aktualizace: Implementujte optimistické aktualizace aktualizací UI ihned po odeslání formuláře s předpokladem, že odeslání bude úspěšné. Vraťte aktualizaci zpět, pokud odeslání selže.
• Integrace s knihovnami pro formuláře: Integrujte useFormStatus s populárními knihovnami pro formuláře, jako jsou Formik nebo React Hook Form, pro správu stavu a validace formuláře. I když tyto knihovny často mají vlastní správu stavu, useFormStatus může být užitečný pro finální fázi odeslání na serverovou akci.

Aspekty internacionalizace (i18n)

Při tvorbě formulářů pro globální publikum je internacionalizace (i18n) klíčová. Zde je, jak zohlednit i18n při použití useFormStatus:

• Lokalizovaná chybová hlášení: Ujistěte se, že chybová hlášení zobrazená uživateli jsou lokalizována do jeho preferovaného jazyka. Toho lze dosáhnout uložením chybových hlášení do překladových souborů a použitím knihovny jako react-intl nebo i18next k získání příslušného překladu.
• Formátování data a čísel: Zpracovávejte formátování data a čísel podle lokalizace uživatele. Použijte knihovny jako Intl.DateTimeFormat a Intl.NumberFormat pro správné formátování těchto hodnot.
• Podpora zprava doleva (RTL): Pokud vaše aplikace podporuje jazyky, které se píší zprava doleva (např. arabština, hebrejština), ujistěte se, že vaše formuláře jsou správně nastylovány, aby vyhovovaly RTL layoutům.
• Validace formuláře: Přizpůsobte pravidla validace formuláře různým lokalitám. Například validace telefonního čísla se může v různých zemích výrazně lišit.

Příklad lokalizovaných chybových hlášení:

// translations/cs.json
{
  "form.error.nameRequired": "Prosím, zadejte své jméno.",
  "form.success.submission": "Děkujeme za odeslání!"
}

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

// Komponenta používající react-intl
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Aspekty přístupnosti

Přístupnost je klíčovým aspektem budování inkluzivních webových aplikací. Zde je několik aspektů přístupnosti, které je třeba mít na paměti při použití useFormStatus:

• ARIA atributy: Použijte ARIA atributy k poskytnutí informací o stavu formuláře asistenčním technologiím. Například použijte aria-busy="true" na odesílacím tlačítku, zatímco formulář čeká na zpracování.
• Popisky (Labels): Ujistěte se, že všechna pole formuláře mají jasné a popisné popisky, které jsou spojeny se vstupními prvky pomocí elementu <label>.
• Chybová hlášení: Zobrazujte chybová hlášení tak, aby byla snadno viditelná a srozumitelná pro uživatele s postižením. Použijte ARIA atributy jako aria-live="assertive" k oznámení chybových hlášení čtečkám obrazovky.
• Navigace klávesnicí: Ujistěte se, že uživatelé mohou formulářem navigovat pouze pomocí klávesnice. Použijte atribut tabindex k řízení pořadí, ve kterém prvky dostávají focus.
• Kontrast barev: Ujistěte se, že barvy textu a pozadí použité ve formuláři mají dostatečný kontrast, aby byly snadno čitelné pro uživatele se zrakovým postižením.

useFormStatus vs. tradiční správa stavu

Tradičně vývojáři v Reactu spravovali stav odesílání formulářů pomocí stavu komponenty (useState) nebo složitějších knihoven pro správu stavu (např. Redux, Zustand). Zde je srovnání těchto přístupů s useFormStatus:

Vlastnost	useFormStatus	useState	Externí správa stavu
Složitost	Nízká	Střední	Vysoká
Integrace se serverovými akcemi	Bezproblémová	Vyžaduje manuální integraci	Vyžaduje manuální integraci
Opakující se kód (Boilerplate)	Minimální	Střední	Značný
Vhodné případy použití	Formuláře odesílané přímo na serverové akce	Jednoduché formuláře s omezeným stavem	Složité formuláře se sdíleným stavem napříč komponentami

useFormStatus exceluje, když vaše formuláře interagují přímo s React Server Actions. Redukuje opakující se kód a zjednodušuje proces. Pro velmi složité formuláře se stavem sdíleným napříč více komponentami však může být stále opodstatněná plnohodnotná knihovna pro správu stavu.

Řešení běžných problémů

Zde jsou některé běžné problémy, se kterými se můžete setkat při používání useFormStatus, a jak je řešit:

• useFormStatus se neaktualizuje:
  • Ujistěte se, že používáte useFormStatus uvnitř elementu <form>, jehož vlastnost action je nastavena na serverovou akci.
  • Ověřte, že je serverová akce správně definována a exportována.
  • Zkontrolujte, zda v serverové akci nejsou nějaké chyby, které by mohly bránit jejímu úspěšnému dokončení.
• Chybová hlášení se nezobrazují:
  • Ujistěte se, že správně zachycujete chyby ve vaší serverové akci a vracíte chybové hlášení.
  • Ověřte, že zobrazujete chybové hlášení ve vaší komponentě pomocí stavu error.
• Indikátor načítání se nezobrazuje:
  • Ujistěte se, že používáte stav pending z useFormStatus k podmíněnému zobrazení indikátoru načítání.
  • Zkontrolujte, zda serverová akce skutečně trvá nějakou dobu (např. simulací zpoždění).

Závěr

useFormStatus poskytuje čistý a efektivní způsob správy stavu odesílání formulářů v React aplikacích využívajících Server Components. Využitím tohoto hooku můžete zjednodušit svůj kód, zlepšit uživatelský zážitek a bezproblémově se integrovat se serverovými akcemi. Tento průvodce pokryl základy useFormStatus, poskytl praktické příklady a probral osvědčené postupy pro jeho efektivní použití. Začleněním useFormStatus do vašich React projektů můžete zefektivnit zpracování formulářů a vytvářet robustnější a uživatelsky přívětivější aplikace pro globální publikum.